Skip to main content
Custom tools connect your agents to your own APIs and internal services, giving them capabilities beyond the pre-built integrations. You define the actions a tool can perform, connect it to Lyzr, and assign it to an agent.

Choose a custom tool type

Lyzr supports two types of custom tool: Custom OpenAPI tools and Custom ACI tools. The main difference is authentication. Use an OpenAPI tool when an API needs no credentials or a static API key. Use an ACI tool when an API uses OAuth 2.0, because ACI manages the token lifecycle for you.

Custom OpenAPI tools

A Custom OpenAPI tool connects to any external service or API that follows the OpenAPI specification. Lyzr parses the spec you provide and defines the tool’s structure, available actions (endpoints), input parameters, and expected output format.

Create an OpenAPI tool

  1. Go to Tools in the sidebar. Tools is the central management area for all pre-built and custom tools.
  2. Select Add Custom Tool, then choose the OpenAPI tool type.
  3. Complete the form using the fields in the following table.
  4. Submit the form. The tool is immediately available to assign to an agent.

Authenticate an OpenAPI tool

OpenAPI tools support two auth types. No Auth is for public or internally trusted APIs that require no credentials, and needs no additional configuration. API Key auth uses a key name and value that you provide once during tool setup:
Lyzr stores the key encrypted and injects it into request headers at execution time. OpenAPI tools do not manage token refresh, so use an ACI tool if you need OAuth with token lifecycle management.

Custom ACI tools

ACI (Agent-Controlled Interface) is Lyzr’s in-house integration layer, built on top of an open-source project. ACI goes beyond OpenAPI by adding full OAuth support, including acquiring access tokens, refreshing them automatically, and storing them encrypted. An ACI tool is defined by two JSON files:
  • app.json describes the application, its metadata, and its security scheme.
  • function.json defines the individual actions the agent can call.
You do not put credentials in these files. You add credentials to the tool in Studio, so they are never written in plain text.
Lyzr is actively open-sourcing the ACI tooling through ACI.dev. Enterprise on-premise deployments can self-host the tooling layer, which keeps all OAuth tokens and credentials within their own infrastructure.

Add an ACI tool

  1. Go to Tools in the sidebar.
  2. Select Add Custom Tool, then select ACI Tool.
  3. Paste your app.json into App JSON and your function.json into Function JSON. To view the required format, choose an option from Select example.
  4. Select Add Tool. The tool appears in your list of tools.
  5. Open the tool, then select Add under Connected Accounts.
  6. Enter a Credential Name, then complete the step for the tool’s auth type:
    • No Auth: The account connects directly with no additional input.
    • API Key: Paste the API key value and select Connect. Lyzr stores the key encrypted and injects it into request headers at execution time.
    • OAuth 2.0: Log in on the provider’s authorization page, grant permissions, and accept the requested scopes. Lyzr then redirects you back and the account is connected. ACI stores the access and refresh tokens encrypted and renews them automatically.
The tool is now ready to assign to an agent. You can add multiple credentials to a tool, whether it uses OAuth 2.0 or an API key. Connected credentials are listed under Connected Accounts. To remove a credential, select Disconnect next to it.

app.json example

The app.json file describes the application, its metadata, and its security scheme, including the auth type, OAuth endpoints, scopes, and client credentials. Sensitive values such as client IDs and secrets are referenced as {{ VARIABLE_NAME }} placeholders, so real values never appear in the file. The following example defines a Gmail integration:

function.json example

The function.json file defines the actions the agent can call, including their parameters, descriptions, and HTTP details. The following example defines a single action that sends an email:

Shared and per-user OAuth

ACI tools that use OAuth 2.0 support two authentication modes, and ACI handles the full token lifecycle in both. Shared auth uses a single set of credentials for all users. You authenticate once during setup, and ACI stores and refreshes the token automatically. Per-user auth has each end user authenticate separately. To use per-user auth, enable per-user auth in the tool settings. Each user’s OAuth flow is handled at inference time through a consent screen, and ACI manages each user’s token refresh cycle.

Assign a custom tool to an agent

Both tool types are assigned to an agent in the same way:
  1. Open the Agent Builder and scroll to Tools.
  2. Select your custom tool from the list.
  3. Enter a description that explains when the agent should use the tool. The description is critical for the LLM to route correctly.
  4. Save the agent.

Delete a custom tool

Deletion is permanent. Deleting a custom tool removes all of its associated metadata, credentials, and configuration.
  1. Go to Tools and locate the tool in the list.
  2. Select Delete.
  3. Confirm in the modal dialog.

Best practices

  • Write specific descriptions. The LLM decides when to call a tool based on its name and description. For example, "Retrieves the current weather for a city using the OpenWeather API" works better than "Gets weather".
  • Choose the right tool type. Use OpenAPI for APIs with no auth or an API key. Use ACI whenever OAuth is involved, because ACI provides the token refresh and encrypted token storage that OpenAPI tools do not.
  • Test before deploying. Use the built-in test runner with sample inputs before you assign a tool to production agents.
  • Use per-user auth for user-facing tools. If a tool acts on behalf of end users, such as reading their calendar or sending from their email, use per-user OAuth instead of shared credentials.
  • Keep tools focused. One tool per action works better than one tool that does many things, because the LLM handles routing.

Next steps